package me.yobol.datastructure.basic.list;

/**
 * 线性表是一种抽象数据类型（ADT),描述了数据的逻辑结构（元素之间一对一）和抽象运算。
 * 
 * 线性表是具有相同数据类型的n（n>=0）个数据元素的有限序列。n为表长，当n为0时，线性表为空。
 * 若用L命名线性表，则线性表则可以表示为
 *          L=(a1,a2,a3,...,an);  //很形象地表示出数据元素之间的邻接关系
 * 其中a1（第一个元素）为线性表的唯一的表头元素；an（最后一个元素）为线性表唯一的表尾元素。
 * 
 * 除表头元素外，所有元素有且仅有一个直接前驱；除表尾元素外，所有元素有且仅有一个直接后继。
 * 
 * @author Yobol
 */
public interface List {
    
    /**
     * 初始化线性表，构造一个空的线性表 
     * 
     */
    void init();
    
    /**
     * 判空操作，即判断线性表中数据元素个数是否为0
     * 
     * @return 
     * @throws java.lang.Exception 
     */
    boolean isEmpty() throws Exception;
    
    /**
     * 判满操作，即判断线性表中的数据元素个数时候大于等于额定元素数。
     * 
     * @return 
     * @throws java.lang.Exception 
     */
    boolean isFull() throws Exception;
    
    /**
     * 返回线性表的长度，即线性表中数据元素的个数
     * 
     * @return 
     * @throws java.lang.Exception 
     */
    int size() throws Exception;
    
    /**
     * 在指定位置上添加指定的节点
     * 
     * @param index
     * @param node
     * @throws java.lang.Exception 
     */
    void insert(int index,Node node) throws Exception;
    
    /**
     * 在表尾添加指定节点
     * 
     * @param node
     * @throws Exception 
     */
    void insert(Node node) throws Exception;
    
    /**
     * 删除指定位置上的节点，并返回该节点
     * 
     * @param index
     * @return 
     * @throws java.lang.Exception 
     */
    Node delete(int index) throws Exception;
    
    /**
     * 获得指定位置上的节点
     * 
     * @param index
     * @return 
     * @throws java.lang.Exception 
     */
    Node getByLocale(int index) throws Exception;
    
    /**
     * 返回线性表中第一个关键字匹配给定值的节点
     * 
     * @param key
     * @return 
     * @throws java.lang.Exception 
     */
    Node getByKey(int key) throws Exception;
    
    /**
     * 打印线性表，按照前后顺序打印输出线性表中所有数据元素的相关属性值
     * 
     * @throws java.lang.Exception
     */
    void print() throws Exception;
    
    /**
     * 清空线性表
     * 
     * @throws Exception 
     */
    void clear() throws Exception;
    
    /**
     * 销毁线性表，并释放线性表所占用的空间
     * 
     * @throws java.lang.Exception
     */
    void destroy() throws Exception;
}
